craft-texture: add bounded float image planes and texture sampling - #1216

Summary

This is the first step of RFC-0032 (storytold/craft-contrib#50, rfcs/0032-shared-pbr-crates.md, the craft-texture row). It adds the crate craft-texture (crates/texture) with MaterialCraft's linear float image planes and their sampling. The code comes from MaterialCraft crates/image/src/lib.rs at 3133062, with its six tests unchanged. No app uses the crate yet. MaterialCraft switches to it in a later pull request.

• Image is a gray or RGBA plane of f32, row-major with the top row first, shared through an Arc. Its fields are private, with width(), height(), kind(), data() and shared_data() getters, so every Image has nonzero sides and a buffer of exactly width × height × channels floats.
• Limits (max_side 8192, max_pixels 2^26, max_bytes 1 GiB) is checked in u64 with checked multiplication before anything is allocated. try_filled, try_generate, try_generate_uv and from_data return an ImageError (BadSize, TooLarge, BadDataLength, OutOfMemory), and try_map, try_to_kind, try_resize and try_to_rgba8_display reserve their memory first. try_resize and try_to_kind check the result against the limits also when they return the image unchanged. The moved constructors without try_ still clamp each side to 1..=8192.
• sample (bilinear) and sample_nearest take (u, v) with (0, 0) at the upper-left corner, as glTF 2.0 section 3.8.3 defines it: "(0, 0) corresponds to the upper left corner" (glTF 2.0). tile selects repeat (glTF REPEAT, 10497) or clamp to edge (CLAMP_TO_EDGE, 33071) on both axes. The texel coordinate (u × width − 0.5 for linear, floor(u × width) for nearest), the wrapping and the four bilinear weights follow the Vulkan specification, sections 20.4.1, 20.6.1 and 20.6.3 (texel coordinates, wrapping, filtering).
• rayon is behind a parallel feature, off by default, and the crate builds for wasm32-unknown-unknown with and without it.
• The crate README has Origin and Migration tables, and the root README.md and Cargo.toml list the crate. No workflow checks the crate for wasm32 yet; adding it to the wasm32 matrix is a separate pull request.

Faults fixed in the moved code, each with a test:

• An Image built by hand with a zero side panicked in get and sample (rem_euclid(0), clamp(0, -1)), and mean divided by zero. A buffer of the wrong length was read with defaults. Private fields and from_data rule both out.
• Repeat clamped the texel coordinate to ±1e9, which changed the repeat period for large finite u, and nearest saturated the i64 cast near 1e19. The normalized coordinate is now reduced first: its fractional part when repeating, kept below 1 so that a tiny negative u stays on the last texel, and -1..=2 when clamping.
• Bilinear used a + (b - a) * t, which gave NaN at a texel center next to an infinite texel and overflowed between f32::MAX and -f32::MAX. It now sums the four weighted texels and skips texels of weight zero.
• The box shrink in resize summed in f32 and overflowed for large HDR values. It sums in f64.
• generate_uv took the pixel-center step from the unclamped size, so a side over 8192 gave centers that stop short of 1.
• linear_to_srgb(NaN) returned −0.055. It returns NaN.

Non-finite pixels are stored as given: to_rgba8_display writes NaN as 0 and clamps, range skips NaN, and mean returns NaN.

Validation

New tests in crates/texture/src/lib.rs. Each of these fails without its fix:

• repeat_keeps_its_period_at_large_coordinates, clamp_selects_the_edges_at_large_coordinates
• bilinear_ignores_zero_weight_texels_and_does_not_overflow, box_shrink_averages_large_hdr_values
• generate_uv_spans_the_clamped_size, srgb_encoding_keeps_nan
• checked_sizes_reject_zero_and_long_sides, checked_sizes_respect_the_pixel_and_byte_limits, checked_sizes_do_not_overflow, from_data_checks_the_length, fallible_operations_check_the_limits, unchanged_results_are_checked_against_the_limits

nearest_follows_the_texel_floor and bilinear_weights_follow_the_fractional_texel_coordinate check the results against the formulas above. small_negative_coordinates_repeat_to_the_last_texel checks that the reduction keeps a tiny negative u on the last texel. non_finite_pixels_have_defined_results and whole_factor_shrink_stays_exact_with_custom_limits pin the non-finite pixel results and the exact box shrink. The six moved tests (sample_survives_huge_coordinates, resource_keys_round_trip, sample_wraps_and_clamps, resize_box_and_bilinear, hostile_sizes_are_clamped, conversions) pass unchanged.

On main at b5b8a77:

• cargo fmt --all -- --check
• cargo clippy -p craft-texture --all-targets -- -D warnings, and with --all-features
• cargo test -p craft-texture (23 passed), and with --features parallel (23 passed)
• cargo check --locked -p craft-texture --target wasm32-unknown-unknown, and with --features parallel
• cargo check --locked --workspace --tests

Summary by CodeRabbit

• New Features
  • Added a texture library for grayscale and RGBA images, with pixel generation, sampling, mapping, resizing, color conversion, and display output.
  • Added configurable image size limits and fallible operations that report invalid sizes or allocation failures.
  • Added image statistics and resource-key utilities.
  • Added optional parallel processing support.
• Documentation
  • Added usage and feature documentation for the texture library, including sampling behavior and image size limits.